Add Sphinx/Doxygen/Breathe documentation framework for phlex and phlex::experimental API by Copilot · Pull Request #323 · Framework-R-D/phlex

Copilot · 2026-02-13T17:09:09Z

Adds a Sphinx + Doxygen + Breathe documentation scaffold under docs/ to generate API reference documentation for phlex and phlex::experimental types, along with dependency requirements and gitignore entries for generated outputs.

Documentation framework

docs/Doxyfile: Doxygen configuration for XML output consumed by Breathe; paths are repo-root-relative — invoke as doxygen docs/Doxyfile from the repository root
docs/source/conf.py: Sphinx configuration with Breathe integration, version 0.1.0 matching CMakeLists.txt; breathe_projects path (../doxygen/xml/) resolves correctly to docs/doxygen/xml/ from docs/source/
docs/source/index.rst: documentation index organized into three toctree sections: Plugin entry points, Algorithm nodes, Data model

Dependency pinning

docs/requirements.txt: sphinx>=9.1,<10, breathe>=4.36,<5, sphinx-rtd-theme>=3.1,<4

API pages — `phlex` namespace

phlex::configuration — parameter access class used by every algorithm
phlex::handle<T> — data product access wrapper passed to algorithm functions
phlex::concurrency — concurrency control struct used in algorithm registration

API pages — `phlex::experimental` namespace

Plugin entry points: module_graph_proxy, source_graph_proxy, graph_proxy, framework_graph, registrar
Algorithm nodes: declared_transform, declared_fold, declared_unfold
Data model: product_store, products

Doxyfile configuration

INPUT = phlex form, OUTPUT_DIRECTORY = docs/doxygen (repo-root-relative)
FILE_PATTERNS = *.hpp *.cpp, EXCLUDE_PATTERNS = */detail/*
PREDEFINED macros for current codebase (BOOST_DLL_ALIAS, PHLEX_DETAIL_REGISTER_PLUGIN)

Housekeeping

.gitignore: added docs/doxygen/ and docs/build/ for generated output
conf.py: module docstring added for ruff D100 compliance

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

greenc-FNAL · 2026-02-13T18:03:02Z

@copilot I think for maximum clarity, it would be better to reset this branch to upstream/main and then re-do the work following the current philosophy, functions/class structure, etc.

Copilot · 2026-02-13T18:10:33Z

@copilot I think for maximum clarity, it would be better to reset this branch to upstream/main and then re-do the work following the current philosophy, functions/class structure, etc.

Done. In commit 412a5ec I reset the branch to main and removed all the stale files from the old base. In 0712ae9 I fixed the docs to match the current codebase (correct class names, macros, version).

The PR now shows only 13 files changed (135 additions, 0 deletions from main): the docs/ directory with Sphinx/Doxygen/Breathe configuration and API pages, plus .gitignore entries for docs build output.

Copilot

Pull request overview

Adds a Sphinx + Doxygen + Breathe documentation scaffold under docs/ to generate API reference documentation for key phlex::experimental types, along with dependency requirements and gitignore entries for generated outputs.

Changes:

Add Sphinx project entrypoint (index.rst) and minimal conf.py wired to Breathe.
Add API reference .rst pages for several phlex::experimental classes.
Add Doxygen configuration + Python requirements, and ignore generated docs artifacts in .gitignore.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/source/index.rst	Adds top-level Sphinx landing page and toctree for API pages.
docs/source/conf.py	Adds Sphinx configuration with Breathe integration.
docs/source/api/graph_proxy.rst	Adds API page for `phlex::experimental::graph_proxy`.
docs/source/api/framework_graph.rst	Adds API page for `framework_graph` and `layer_sentry`.
docs/source/api/registrar.rst	Adds API page for `phlex::experimental::registrar`.
docs/source/api/declared_transform.rst	Adds API page for `declared_transform`.
docs/source/api/declared_fold.rst	Adds API page for `declared_fold`.
docs/source/api/declared_unfold.rst	Adds API page for `declared_unfold`.
docs/source/api/product_store.rst	Adds API page for `product_store`.
docs/source/api/products.rst	Adds API page for `products`.
docs/requirements.txt	Adds Python dependencies for building docs.
docs/Doxyfile	Adds Doxygen configuration to emit XML for Breathe.
.gitignore	Ignores generated Doxygen/Sphinx build output directories.

Comments suppressed due to low confidence (1)

docs/requirements.txt:4

The PR description says dependencies are “pinned”, but requirements.txt uses version ranges (e.g., >=9.1,<10) which will allow new releases and can change doc build output over time. Either pin exact versions (e.g., ==...) to match the description, or update the description to reflect that these are minimum/compatible ranges. Also remove the trailing blank line at EOF to avoid generating a 4th empty requirement line.

sphinx>=9.1,<10
breathe>=4.36,<5
sphinx-rtd-theme>=3.1,<4

docs/source/conf.py

greenc-FNAL · 2026-02-13T21:05:26Z

@phlexbot python-fix

github-actions · 2026-02-13T21:06:02Z

Automatic ruff fixes pushed (commit af87c94).
⚠️ Note: Some issues may require manual review and fixing.

codecov · 2026-02-13T21:15:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##             main     #323      +/-   ##
==========================================
+ Coverage   84.94%   85.03%   +0.08%     
==========================================
  Files         127      127              
  Lines        3341     3341              
  Branches      574      574              
==========================================
+ Hits         2838     2841       +3     
  Misses        306      306              
+ Partials      197      194       -3

Flag	Coverage Δ
unittests	`85.03% <ø> (+0.08%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 2 files with indirect coverage changes

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ce7ce80...5bf370b. Read the comment docs.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

greenc-FNAL · 2026-03-04T18:56:38Z

@copilot This PR (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your original prompt for this task.

Copilot · 2026-03-04T18:59:54Z

@copilot This PR (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date wi...

Re-evaluated after rebase. The only needed fix was removing the layer_sentry reference from framework_graph.rst — that class was deleted from the codebase since my last update. All other documented classes (graph_proxy, framework_graph, registrar, declared_transform, declared_fold, declared_unfold, product_store, products) verified present. Dependency versions, macros, and project version all still current. Done in 234e183.

Copilot

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 2 comments.

docs/Doxyfile

docs/source/conf.py

greenc-FNAL · 2026-03-09T17:29:16Z

@copilot https://gh.io/copilot-coding-agent-docs #323 (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your original prompt for this task. Please also extend the goals of the original prompt to cover the entire phlex namespace, not just phlex::experimental.

Copilot · 2026-03-09T17:33:20Z

@copilot https://gh.io/copilot-coding-agent-docs #323 (branch copilot/update-branch-with-main-again) has been rebased against main once...

Done in 958e762:

Doxyfile paths fixed: INPUT = phlex form and OUTPUT_DIRECTORY = docs/doxygen are now repo-root-relative; canonical invocation is doxygen docs/Doxyfile from the repo root. The Sphinx breathe_projects path (../doxygen/xml/ from docs/source/) already resolves correctly to docs/doxygen/xml/.

phlex namespace added: three new API pages covering the root namespace:

phlex::configuration — parameter access for algorithms
phlex::handle<T> — data product access wrapper passed to algorithm functions
phlex::concurrency — concurrency control struct used in registration

index.rst reorganized into three toctree sections: Plugin entry points, Algorithm nodes, Data model.

Copilot

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 6 comments.

docs/requirements.txt

docs/source/conf.py

docs/source/index.rst

docs/source/api/handle.rst

docs/source/conf.py

docs/Doxyfile

greenc-FNAL · 2026-03-16T16:08:23Z

Review the full CodeQL report for details.

greenc-FNAL · 2026-03-21T03:07:05Z

@copilot PR #323 (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your original prompt for this task. Please ensure the documentation added by this PR remains accurate and up-to-date with respect to changes to main since the last rebase.

Copilot · 2026-03-21T03:10:08Z

@copilot PR #323 (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your ori...

Re-evaluated after rebase. The only commit to main since the last rebase was workflow/action maintenance (#434) — no new public API classes were added. All 13 documented classes verified present (phlex::configuration, phlex::handle, phlex::concurrency, and 10 phlex::experimental types). Version, macros, and Doxyfile paths are still correct.

Also fixed the outstanding review issue: removed the nonexistent _templates path from conf.py to prevent Sphinx warnings (1722c43). Trailing-blank-line issues from the previous review were already resolved by the rebase.

Copilot

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 1 comment.

docs/source/index.rst

…work This commit introduces the foundational infrastructure for documenting the C++ codebase using a Sphinx, Doxygen, and Breathe toolchain. Key changes include: - A new `docs/` directory to house all documentation-related files. - Configuration files for Sphinx (`conf.py`) and Doxygen (`Doxyfile`). - A `requirements.txt` file listing the necessary Python dependencies for building the documentation. - The `phlex/core/graph_proxy.hpp` header has been fully documented with Doxygen comments to serve as a style guide and working example. - An initial Sphinx structure in `docs/source/` that integrates the Doxygen XML output via Breathe, making the `graph_proxy` documentation available on the documentation website. Initial plan Update docs: pin latest deps, fix version, expand API coverage, add .gitignore entries Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Reset branch to main and re-apply docs-only changes Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Fix docs for current codebase: correct version, class names, macros, and .gitignore Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Add module docstring to docs/source/conf.py for ruff D100 compliance Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Apply ruff fixes Ignore `mypy` errors

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

…ing entry points) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

…docs (configuration, handle, concurrency) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Agent-Logs-Url: https://github.com/Framework-R-D/phlex/sessions/c907fe9c-6f80-4160-ac32-440e2909ef30

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI assigned Copilot and greenc-FNAL Feb 13, 2026

Copilot started work on behalf of greenc-FNAL February 13, 2026 17:09 View session

Copilot AI changed the title ~~[WIP] Update branch with latest main and enhance features~~ Update Sphinx/Doxygen/Breathe docs: pin latest deps, fix config, expand API coverage Feb 13, 2026

Copilot AI requested a review from greenc-FNAL February 13, 2026 17:19

Copilot finished work on behalf of greenc-FNAL February 13, 2026 17:19

Copilot started work on behalf of greenc-FNAL February 13, 2026 18:03 View session

Copilot finished work on behalf of greenc-FNAL February 13, 2026 18:11

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 0712ae9 to 2095c80 Compare February 13, 2026 18:25

greenc-FNAL changed the base branch from jules-feature-sphinx-doxygen-breathe-setup to main February 13, 2026 18:30

greenc-FNAL marked this pull request as ready for review February 13, 2026 18:31

Copilot AI review requested due to automatic review settings February 13, 2026 18:31

Copilot started reviewing on behalf of greenc-FNAL February 13, 2026 18:31 View session

Copilot AI reviewed Feb 13, 2026

View reviewed changes

docs/source/conf.py Outdated Show resolved Hide resolved

Copilot started work on behalf of greenc-FNAL February 13, 2026 20:58 View session

Copilot finished work on behalf of greenc-FNAL February 13, 2026 21:00

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 824f679 to a7a5bf2 Compare February 14, 2026 00:18

greenc-FNAL marked this pull request as draft February 14, 2026 01:19

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch 2 times, most recently from dcbc52d to e416cbc Compare February 20, 2026 17:44

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from e416cbc to 85a095f Compare February 24, 2026 16:32

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 85a095f to a62c7df Compare March 4, 2026 18:52

Copilot started work on behalf of greenc-FNAL March 4, 2026 18:56 View session

Copilot started reviewing on behalf of greenc-FNAL March 4, 2026 21:06 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

docs/Doxyfile Outdated Show resolved Hide resolved

docs/source/conf.py Show resolved Hide resolved

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 3b11ebf to a04ec85 Compare March 9, 2026 16:43

Copilot started work on behalf of greenc-FNAL March 9, 2026 17:29 View session

Copilot AI changed the title ~~Add Sphinx/Doxygen/Breathe documentation framework for phlex::experimental API~~ Add Sphinx/Doxygen/Breathe documentation framework for phlex and phlex::experimental API Mar 9, 2026

Copilot finished work on behalf of greenc-FNAL March 9, 2026 17:34

greenc-FNAL requested a review from Copilot March 9, 2026 18:30

Copilot started reviewing on behalf of greenc-FNAL March 9, 2026 18:31 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch 2 times, most recently from 4dc2b20 to 267fc43 Compare March 16, 2026 16:04

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch 2 times, most recently from 8934e85 to 7ab18e8 Compare March 21, 2026 02:24

Copilot started work on behalf of greenc-FNAL March 21, 2026 03:07 View session

Copilot finished work on behalf of greenc-FNAL March 21, 2026 03:10

greenc-FNAL requested a review from Copilot March 21, 2026 03:38

Copilot started reviewing on behalf of greenc-FNAL March 21, 2026 03:38 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

docs/source/index.rst Outdated Show resolved Hide resolved

google-labs-jules bot and others added 6 commits March 23, 2026 08:44

Remove layer_sentry reference (class no longer exists in codebase)

54bdb36

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Add module_graph_proxy and source_graph_proxy API pages (new user-fac…

c6ff11b

…ing entry points) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Fix Doxyfile paths for repo-root invocation; add phlex-namespace API …

c178964

…docs (configuration, handle, concurrency) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Remove nonexistent _templates path from Sphinx conf.py

8e3295e

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Agent-Logs-Url: https://github.com/Framework-R-D/phlex/sessions/c907fe9c-6f80-4160-ac32-440e2909ef30

Remove sphinx-quickstart boilerplate

5bf370b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from b4afc05 to 5bf370b Compare March 23, 2026 13:44

Conversation

Copilot AI commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation framework

Dependency pinning

API pages — phlex namespace

API pages — phlex::experimental namespace

Doxyfile configuration

Housekeeping

Uh oh!

greenc-FNAL commented Feb 13, 2026

Uh oh!

Copilot AI commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

greenc-FNAL commented Feb 13, 2026

Uh oh!

github-actions bot commented Feb 13, 2026

Uh oh!

codecov bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

greenc-FNAL commented Mar 4, 2026

Uh oh!

Copilot AI commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

greenc-FNAL commented Mar 9, 2026

Uh oh!

Copilot AI commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greenc-FNAL commented Mar 16, 2026

Uh oh!

greenc-FNAL commented Mar 21, 2026

Uh oh!

Copilot AI commented Mar 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 13, 2026 •

edited

Loading

API pages — `phlex` namespace

API pages — `phlex::experimental` namespace

codecov bot commented Feb 13, 2026 •

edited

Loading